Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added automatic push of docs to scitools-docs/iris. #2610

Merged
merged 1 commit into from
Jun 27, 2017
Merged

Added automatic push of docs to scitools-docs/iris. #2610

merged 1 commit into from
Jun 27, 2017

Conversation

pelson
Copy link
Member

@pelson pelson commented Jun 21, 2017

Notice: this is a SciTools/iris branch, and should be deleted once merged.

I've added a final step to our doctest build matrix to push the built docs to https://github.com/SciTools-docs/iris. The setup currently is:

  • push a folder named by the branch being built (e.g master) to the gh-pages branch
  • Python 3 is used as doctr only supports 3.5+. This means we aren't pushing any of the GRIB stuff currently (not Py3 compatible).
  • I've used a separate organisation for several reasons:
    • it isolates the impact of a token being leaked accidentally (nobody can modify SciTools/iris itself
    • it prevents the automatic building of docs pushing a repository artificially high up the list of repositories in github.com/SciTools
    • We don't need to worry about the size of the repository - it is Iris' docs only, and nobody normally will be cloning it (though there is a question in my mind about performance that says that doctr would need to pull the repository)
    • It is easy to rinse and repeat for other project docs (e.g. cartopy)
    • The downsides:
      • Another organisation, with an entirely different set of teams etc. (still, most people don't actually need write access to it)
      • Falls under a different domain scitools-docs.github.io. We could make this a subdomain of scitools.org.uk (e.g. docs.scitools.org.uk)
      • It isn't readthedocs (we are likely to have hit time/size limits with that, and there is an advertising program that, whilst reasonable, doesn't sit too comfortably with me)

The results of this can be seen in https://github.com/SciTools-docs/iris and https://scitools-docs.github.io/iris/travis-docs/. (this is also the reason for the branch being on SciTools)

@pelson pelson requested a review from bjlittle June 21, 2017 11:25
@pelson
Copy link
Member Author

pelson commented Jun 21, 2017 •
edited by pp-mo
Loading

Also, we will want to:

  • manually delete the travis-docs folder in the scitools-docs organisation
  • ensure that more people than just me have access to scitools-docs

@pelson
Copy link
Member Author

pelson commented Jun 21, 2017

Looks like there is a genuine problem with master, not with this change.

@cpelley
Copy link

cpelley commented Jun 22, 2017 •
edited
Loading

It isn't readthedocs

Was your original motivations around readthedocs about its abilities around versioning? Something else?

@bjlittle bjlittle self-assigned this Jun 22, 2017
@bjlittle
Copy link
Member

@pelson I'm working on fixing master now ... mostly changes from numpy bumping from 1.12.1 to 1.13.0, and there may be fall-out from netcdf4 bumping from 1.2.8 to 1.2.9 ...

@pelson
Copy link
Member Author

pelson commented Jun 22, 2017

Was your original motivations around readthedocs about its abilities around versioning? Something else?

I'm not 100% I've understood, but here are my (very opinionated) thoughts on RTD:

  • It adds a layer of complexity to build Iris' docs on RTD's infra (not RTD's fault, we have an unreasonably/unnecessarily complex doc build process)
  • we already build the docs with every commit, we don't need to do that work again
  • advertising is not something I'm especially keen to add to our docs (though I have no problem with RTD itself having done so - it makes a lot of sense to help them cover the substantial costs of operation)
  • doctr made it sustainable to maintain code to push from a repository (I've written my fair share of this kind of code, but didn't have the space to generalise as has been done in doctr)

To be clear, I'm only proposing this change as a means of seeing dev docs. We can talk about tagged builds, but that falls out of scope for this initial PR.

@cpelley
Copy link

cpelley commented Jun 22, 2017

Thanks @pelson, cool!

@bjlittle bjlittle added this to the v2.0 milestone Jun 23, 2017
@bjlittle
Copy link
Member

@pelson Awesome! 👍

Rebase when #2616 is merged, and let's get this merged 😄

@pelson
Copy link
Member Author

pelson commented Jun 26, 2017

Rebased.

@pp-mo pp-mo merged commit e7766bf into master Jun 27, 2017
@pp-mo pp-mo deleted the travis-docs branch June 27, 2017 17:33
@pp-mo
Copy link
Member

pp-mo commented Jun 28, 2017

And we now have ... https://scitools-docs.github.io/iris/master/
Which is simply brilliant ! 🍾 🥇

@pelson
Copy link
Member Author

pelson commented Jun 28, 2017

Thanks for reviewing and merging.

marqh pushed a commit to marqh/iris that referenced this pull request Jul 14, 2017
@pelson @marqh
Added automatic push of docs to scitools-docs/iris. (SciTools#2610)
3f2ad25
@pp-mo pp-mo mentioned this pull request Oct 19, 2017
Merged
pp-mo
pp-mo reviewed Oct 19, 2017
View reviewed changes
.travis.yml
echo `make clean html`;
make doctest;
cd ../../;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prevents any test failure being recognised by Travis !

pp-mo
pp-mo reviewed Oct 19, 2017
View reviewed changes
.travis.yml
python aggregate_directory.py --checkonly;
cd ../../../../;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prevents any test failure being recognised by Travis !

@rcomer rcomer mentioned this pull request Aug 24, 2021
Closed
@bjlittle bjlittle mentioned this pull request Mar 2, 2022
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@pp-mo pp-mo pp-mo left review comments

@bjlittle bjlittle Awaiting requested review from bjlittle

Assignees

@bjlittle bjlittle

Labels
None yet
Projects
None yet
Milestone
v2.0.0
Development

Successfully merging this pull request may close these issues.
4 participants
@pelson @cpelley @bjlittle @pp-mo